home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / pgp / pgp26uib.lzh / PGP26UI / DOC / PGFORMAT.DOC < prev    next >
Text File  |  1994-06-19  |  34KB  |  789 lines
  1. Internal Data Structures Used by PGP 2.3 (14 Jun 93)
  2. ==========================================================
  3.  
  4. This appendix describes the file formats used externally by Pretty
  5. Good Privacy (PGP), the RSA public key cryptography application.  The
  6. intended audience includes software engineers trying to port PGP to
  7. other hardware environments or trying to implement other PGP-
  8. compatible cryptography products, or anyone else who is curious.
  9.  
  10. [To be included: a description of ASCII armor.  And ASCII armored
  11. file is just like a binary file described here, but with an extra
  12. layer of encoding added, framing lines, and a checksum at the end.]
  13.  
  14.  
  15. Byte Order
  16. ----------
  17.  
  18. All integer data used by PGP is externally stored most significant
  19. byte (MSB) first, regardless of the byte order used internally by the
  20. host CPU architecture.  This is for cross-compatibility of messages
  21. and keys between hosts.  This covers multiprecision RSA integers, bit
  22. count prefix fields, byte count prefix fields, checksums, key IDs, and
  23. timestamps.
  24.  
  25. The MSB-first byte order for external packet representation was
  26. chosen only because many other crypto standards use it.
  27.  
  28.  
  29. Multiprecision Integers
  30. -----------------------
  31.  
  32. RSA arithmetic involves a lot of multiprecision integers, often
  33. having hundreds of bits of precision.  PGP externally stores a
  34. multiprecision integer (MPI) with a 16-bit prefix that gives the
  35. number of significant bits in the integer that follows.  The integer
  36. that follows this bitcount field is stored in the usual byte order, 
  37. with the MSB padded with zero bits if the bitcount is not a multiple
  38. of 8.  The bitcount always specifies the exact number of significant
  39. bits.  For example, the integer value 5 would be stored as these
  40. three bytes:
  41.  
  42.     00 03 05
  43.  
  44. An MPI with a value of zero is simply stored with the 16-bit bitcount 
  45. prefix field containing a 0, with no value bytes following it.
  46.  
  47.  
  48.  
  49. Key ID
  50. ------
  51.  
  52. Some packets use a "key ID" field.  The key ID is the least
  53. significant 64 bits of the RSA public modulus that was involved in
  54. creating the packet.  For all practical purposes it unique to each 
  55. RSA public key.
  56.  
  57.  
  58. User ID
  59. -------
  60.  
  61. Some packets contain a "user ID", which is an ASCII string that
  62. contains the user's name.  Unlike a C string, the user ID has a
  63. length byte at the beginning that has a byte count of the rest of the
  64. string.  This length byte does not include itself in the count.
  65.  
  66.  
  67. Timestamp
  68. ---------
  69.  
  70. Some packets contain a timestamp, which is a 32-bit unsigned integer
  71. of the number of seconds elapsed since 1970 Jan 1 00:00:00 GMT.  This
  72. is the standard format used by Unix timestamps.  It spans 136 years. 
  73.  
  74.  
  75.  
  76. Cipher Type Byte (CTB)
  77. ----------------------
  78.  
  79. Many of these data structures begin with a Cipher Type Byte (CTB),
  80. which specifies the type of data structure that follows it.  The CTB 
  81. bit fields have the following meaning (bit 0 is the LSB, bit 7 is the
  82. MSB):
  83.  
  84. Bit 7:     Always 1, which designates this as a CTB
  85. Bit 6:     Reserved.
  86. Bits 5-2:  CTB type field, specifies type of packet that follows
  87.            0001 - public-key-encrypted packet
  88.            0010 - secret-key-encrypted (signature) packet
  89.            0101 - Secret key certificate
  90.            0110 - Public key certificate
  91.            1000 - Compressed data packet
  92.            1001 - Conventional-Key-Encrypted data
  93.            1011 - Raw literal plaintext data, with filename and mode
  94.            1100 - Keyring trust packet
  95.            1101 - User ID packet, associated with public or secret key
  96.            1110 - Comment packet
  97.            Other CTB packet types are unimplemented.
  98. Bits 1-0:  Length-of-length field:
  99.            00 - 1 byte packet length field follows CTB
  100.            01 - 2 byte packet length field follows CTB
  101.            10 - 4 byte packet length field follows CTB
  102.            11 - no length field follows CTB, unknown packet length.
  103.            The 8-, 16-, or 32-bit packet length field after the CTB 
  104.            gives the length in bytes of the rest of the packet, not
  105.            counting the CTB and the packet length field.
  106.  
  107.  
  108.  
  109. RSA public-key-encrypted packet
  110. -------------------------------
  111.  
  112. Offset  Length  Meaning
  113. 0       1       CTB for RSA public-key-encrypted packet
  114. 1       2       16-bit (or maybe 8-bit) length of packet
  115. 3    1    Version byte (=2).  May affect rest of fields that follow.
  116. 4       8       64-bit Key ID
  117. 12    1    Algorithm byte for RSA (=1 for RSA).  
  118.         --Algorithm byte affects field definitions that follow.
  119. 13      ?       RSA-encrypted integer, encrypted conventional key
  120.                 packet.  (MPI with bitcount prefix)
  121.  
  122. The conventionally-encrypted ciphertext packet begins right after the 
  123. RSA public-key-encrypted packet that contains the conventional key.
  124.  
  125.  
  126.  
  127. Signature packet
  128. ----------------
  129.  
  130. Offset  Length  Meaning
  131. 0       1       CTB for secret-key-encrypted (signed) packet
  132. 1       2       16-bit (or maybe 8-bit) length of packet
  133. 3    1    Version byte (=2).  May affect rest of fields that follow.
  134.  
  135. 4    1    Length of following material that is implicitly included 
  136.         in MD calculation.
  137. 5    1    Signature classification field (see below). 
  138.         Implicitly append this to message for MD calculation.
  139. 6    4    32-bit timestamp of when signature was made.  
  140.         Implicitly append this to message for MD calculation.
  141. 10      2       Validity period, in number of DAYS (0 means forever)
  142.         Implicitly append this to message for MD calculation.
  143.  
  144. 12      8       64-bit Key ID
  145. 20    1    Algorithm byte for public key scheme (RSA=0x01).  
  146.         --Algorithm byte affects field definitions that follow.
  147. 21    1    Algorithm byte for message digest (MD5=0x01).
  148. 22    2    First 2 bytes of the Message Digest inside the 
  149.         RSA-encrypted integer, to help us figure out if we 
  150.         used the right RSA key to check the signature.
  151. 24      ?       RSA-encrypted integer, encrypted message digest
  152.                 (MPI with bitcount prefix).
  153.  
  154. If the plaintext that was signed is included in the same file as the
  155. signature packet, it begins right after the RSA secret-key-signed 
  156. packet that contains the message digest.  The plaintext has a
  157. "literal" CTB prefix.
  158.  
  159. The validity period field is generally only used for certifying keys. 
  160. It should be set to 0 otherwise, for regular message signatures.  It
  161. may be useful for PEM-like capabilities in future versions of PGP. 
  162. PGP 2.3 will always just set it to 0, and will ignore it.
  163.  
  164. There is a length field that specifies how many bytes of material is
  165. implicitly included in the MD calculation.  If this length field is
  166. 5, it means the following 1-byte classification field and the 4-byte
  167. timestamp are included in the signature packet.  If the length byte
  168. is 7, it means the 2-byte validity period is also included.  In PGP
  169. 2.3, we are using a length field of 5 for the material to be included
  170. in the MD calculation, so the validity period is unused and
  171. unincluded, and is assumed to be zeroed.  This makes the whole
  172. signature certificate shorter.
  173.  
  174. The signature classification field describes what kind of 
  175. signature certificate this is.  There are various hex values:
  176.     00 -    Signature of a message or document, binary image.  
  177.     01 -    Signature of a message or document, canonical text.  
  178.     10 -    Key certification, generic.  Only version of key
  179.         certification supported by PGP 2.0.
  180.         Material signed is public key pkt and User ID pkt.
  181.     11 -    Key certification, persona.  No attempt made at all 
  182.         to identify the user with a real name.
  183.         Material signed is public key pkt and User ID pkt.
  184.     12 -    Key certification, casual identification.  Some
  185.         casual attempt made to identify user with his name.
  186.         Material signed is public key pkt and User ID pkt.
  187.     13 -    Key certification, positive ID.  Heavy-duty
  188.         identification efforts, photo ID, direct contact 
  189.         with personal friend, etc.
  190.         Material signed is public key pkt and User ID pkt.
  191.     20 -     Key compromise.  User signs his own compromise
  192.         certificate.  Independent of user ID associations.
  193.         Material signed is public key pkt ONLY.
  194.     30 -     Key/userid revocation.  User can sign his own 
  195.         revocation to dissolve an association between a key
  196.         and a user ID, or certifier may revoke his previous 
  197.         certification of this key/userid pair. 
  198.         Material signed is public key pkt and User ID pkt.
  199.     40 -    Timestamping a